<p class="Head1"><help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX"><help:key-word value="programming a shared library for %PRODUCTNAME Calc" tag="kw66914_1"/></help:case><help:default><help:key-word value="programming external DLL functions for %PRODUCTNAME Calc" tag="kw66914_8"/></help:default></help:switch><help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX"><help:key-word value="shared library for programming in %PRODUCTNAME Calc" tag="kw66914_7"/></help:case><help:default><help:key-word value="external DLL functions for programming in %PRODUCTNAME Calc" tag="kw66914_6"/></help:default></help:switch><help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX"><help:key-word value="functions of the shared library for %PRODUCTNAME Calc" tag="kw66914_5"/></help:case><help:default><help:key-word value="functions of the %PRODUCTNAME Calc add-in DLL" tag="kw66914_4"/></help:default></help:switch><help:key-word value="add-in category" tag="kw66914_3" xmlns:help="http://openoffice.org/2000/help"/><help:key-word value="add-in for programming in %PRODUCTNAME Calc" tag="kw66914_2" xmlns:help="http://openoffice.org/2000/help"/>Add-in for Programming in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc</p>
<p class="Paragraph">An Add-In can be attached to <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc, which is an external programming module providing additional functions for working with spreadsheets. These are displayed in the Function AutoPilot in the <span class="T1">Add-In</span> category. If you would like to program such an Add-In yourself, you can learn here which functions must be exported by the <help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX">Shared Library</help:case><help:default>external DLL</help:default></help:switch> so that the Add-In can be successfully attached.</p>
<p class="Paragraph"><help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> searches the path defined in <span class="T1">Tools - Options - <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> - Path</span> for modules according to a subordinate "addin" and examines these against a suitable <help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX">Shared library</help:case><help:default>DLL</help:default></help:switch>. In order for this <help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX"/><help:default>DLL</help:default></help:switch> to be recognized by <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname>, it must have certain properties, as explained in the following. This information allows you to program your own AddIn for AutoPilot: Functions of <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc.</p>
<p class="Paragraph">Included in the program package are two samples of an Add-In interface of <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc. If you indicated during installation of the program that Add-Ins are also to be installed, an "addin" directory is included in the Office directory, which contains sample DLLs as well as an additional "source" subdirectory listing the source code.</p>
<p class="Paragraph">A description of the add-in functions provided by the sample DLLs can be found in the <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Help about the Function AutoPilot in the <help:link Id="66872" Eid="beispiele" xmlns:help="http://openoffice.org/2000/help">add-in category</help:link>.</p>
</span></th></tr></table>
<p class="Paragraph"/>
<p class="Head2">The Add-In Concept</p>
<p class="Paragraph">Each Add-In library provides several functions. Some functions are used for management purposes and must follow a certain convention. Through these functions information about other functions is available, which make up the extension of <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc. You can choose any name for these functions. However, they must also follow certain rules regarding parameter passing. The exact naming and calling conventions vary for different platforms. Under Windows, the Pascal conventions are used, among others, because Pascal is still widely common.</p>
<p class="Head3">Functions of <help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX">Shared Library</help:case><help:default>AddIn DLL</help:default></help:switch></p>
<p class="Paragraph">At a minimum, the management functions <help:link Id="66914" Eid="getfunctioncount" xmlns:help="http://openoffice.org/2000/help">GetFunctionCount</help:link> and <help:link Id="66914" Eid="getfunctiondata" xmlns:help="http://openoffice.org/2000/help">GetFunctionData</help:link> must exist. Using these, the functions as well as parameter types and return values can be determined. For return values, the Double and String types are supported. For additional parameters, the cell areas <help:link Id="66914" Eid="doublearray" xmlns:help="http://openoffice.org/2000/help">Double Array</help:link>, <help:link Id="66914" Eid="stringarray" xmlns:help="http://openoffice.org/2000/help">String Array</help:link>, and <help:link Id="66914" Eid="cellarray" xmlns:help="http://openoffice.org/2000/help">Cell Array</help:link> are supported.</p>
<p class="Paragraph">Parameters are passed using references. Therefore, a change of these values is basically possible. However, this is not supported in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc because it does not make sense within spreadsheets.</p>
<p class="Paragraph">Libraries can be reloaded during load time and their contents can be analyzed using the two management functions. For each function, information about parameter number and type, application internal and real names as well as management numbers is available.</p>
<p class="Paragraph">The functions are called synchronously and return their results immediately. Real time functions (asynchronous functions) are also possible; however, they are not explained in detail because of their complexity.</p>
<p class="Head2">General information about the interface</p>
<p class="Paragraph">The maximum number of parameters in an Add-In function attached to <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc is 16: one result value and a maximum of 15 input function parameters.</p>
<p class="Paragraph">The data types are defined as follows:</p>
<p class="Paragraph">Following you will find a description of those functions, which are called at the <help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX">Shared Library</help:case><help:default>external DLL</help:default></help:switch>.</p>
<p class="Paragraph">For all <help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX">Shared Library</help:case><help:default>DLL</help:default></help:switch> functions applies:</p>
<p class="Paragraph">Input: Any number of types (double&, char*, double*, char**, Cel area), where the <help:link Id="66914" Eid="zellbereich" xmlns:help="http://openoffice.org/2000/help">Cell area</help:link> is an array of types double array, string array, or cell array.</p>
<p class="Paragraph">Returns the number of functions without the management functions of the reference parameter. Each function has a unique number between 0 and nCount-1. This number will be needed for the <help:link Id="66914" Eid="getfunctiondata" xmlns:help="http://openoffice.org/2000/help">GetFunctionData</help:link> and <help:link Id="66914" Eid="getparameterdescription" xmlns:help="http://openoffice.org/2000/help">GetParameterDescription</help:link> functions later.</p>
<p class="Paragraph">Output: Reference to a variable, which is supposed to contain the number of Add-In functions. E.g.: If the Add-In provides 5 functions for <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc, then nCount=5.</p>
<p class="Paragraph">Input: Function number between 0 and nCount-1, inclusively.</p>
<p class="Paragraph">char* pFuncName:</p>
<p class="Paragraph">Output: Function name as seen by the programmer, as it is named in the <help:switch select="System" xmlns:help="http://openoffice.org/2000/help"><help:case select="UNIX">Shared Library</help:case><help:default>DLL</help:default></help:switch>. This name does not determine the name used in the function AutoPilot.</p>
<p class="Paragraph">USHORT& nParamCount:</p>
<p class="Paragraph">Output: Number of parameters in AddIn function. This number must be greater than 0, because there is always a result value; the maximum value is 16.</p>
<p class="Paragraph">Paramtype* peType:</p>
<p class="Paragraph">Output: Pointer to an array of exactly 16 variables of type Paramtype. The first nParamCount entries are filled with the suitable type of parameter.</p>
<p class="Paragraph">char* pInternalName:</p>
<p class="Paragraph">Output: Function name as seen by the user, as it appears in the Function AutoPilot. May contain umlauts.</p>
<p class="Paragraph">The pFuncName and pInternalName parameters are char arrays, which are implemented with size 256 in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc.</p>
<p class="Paragraph">Provides a brief description of the AddIn function and its parameters. As an option, this function can be used to show a function and parameter description in the function AutoPilot.</p>
<p class="Paragraph">Input: Number of the function in the library; between 0 and nCount-1.</p>
<p class="Paragraph">USHORT& nParam:</p>
<p class="Paragraph">Input: Indicates, for which parameter the description is provided; parameters start at 1. If nParam is 0, the description itself is supposed to be provided in pDesc; in this case, pName does not have any meaning.</p>
<p class="Paragraph">char* pName:</p>
<p class="Paragraph">Output: Takes up the parameter name or type, e.g. the word "Number" or "String" or "Date", etc. Implemented in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc as char[256].</p>
<p class="Paragraph">char* pDesc:</p>
<p class="Paragraph">Output: Takes up the description of the parameter, e.g. "Value, at which the universe is to be calculated." Implemented in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc as char[256].</p>
<p class="Paragraph">pName and pDesc are char arrays; implemented in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc with size 256. Please note that the space available in the Function AutoPilot is limited and that the 256 characters cannot be fully used.</p>
<p class="Paragraph">The following tables contain information about which data structures must be provided by an external program module in order to pass cell areas. <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc distinguishes between three different arrays, depending on the data type.</p>
<p class="Paragraph">As a parameter, a cell area with values of the Number/Double type can be passed. A double array in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc is defined as follows:</p>
<p class="Paragraph">Error number, where the value 0 is defined as "no error." If the element comes from a formula cell the error value is determined by the formula.</p>
<p class="Paragraph">A cell area, which contains values of data type Text and is passed as a string array. A string array in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc is defined as follows:</p>
<p class="Paragraph">Error number, where the value 0 is defined as "no error." If the element comes from a formula cell the error value is determined by the formula.</p>
<p class="Paragraph">Length of the following string, including closing zero byte. If the length including closing zero byte equals an odd value a second zero byte is added to the string so that an even value is achieved. Therefore, Len is calculated using ((StrLen+2)&~1).</p>
<p class="Paragraph">Cel arrays are used to call cell areas containing text as well as numbers. A cell array in <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Calc is defined as follows:</p>
<p class="Paragraph">Error number, where the value 0 is defined as "no error." If the element comes from a formula cell the error value is determined by the formula.</p>
<p class="Paragraph">If type == 0: 8 byte IEEE variable of type double/floating point</p>
<p class="Paragraph">If type == 1: Length of the following string, including closing zero byte. If the length including closing zero byte equals an odd value a second zero byte is added to the string so that an even value is achieved. Therefore, Len is calculated using ((StrLen+2)&~1).</p>
